package com.alkalinesolutions.json.core;

import java.util.List;
import java.util.Map;

/**
 * Interface for Java object serializers. These expect all data input to be one
 * of:
 * <ul>
 * <li>the value <code>null</code></li>
 * <li>a Java <code>String</code></li>
 * <li>a Java <code>Number</code>, such as Integer, Short, BigDecimal, ...</li>
 * <li>One of the two valid values for <code>Boolean</code></li>
 * <li>a JSON Object in the form of a
 * <code>Map&lt;String, ? extends Object&gt;</code></li>
 * <li>a JSON Array in the form of a <code>List&lt;? extends Object&gt;</code></li>
 * <li>a JSON Array in the form of an <code>Object[]</code></li>
 * </ul>
 * 
 * @author David Waite &lt;<a href='mailto:david@alkaline-solutions.com'>david@alkaline-solutions.com</a>&gt;
 */
public interface Serializer {
	/**
	 * Serialize a JSONText object, given as a <code>Map</code>.
	 * 
	 * @param object
	 *            map of key/value pairs. Values may be of any type described
	 *            above.
	 * @return String holding text
	 * @throws JSONException
	 *             on errors, such as giving values which are not supported.
	 */
	String serialize(Map<String, ? extends Object> object) throws JSONException;

	/**
	 * Serialize a JSONText array, given as a <code>List</code>.
	 * 
	 * @param array
	 *            list of values, which may be of any type described above.
	 * @return String holding text
	 * @throws JSONException
	 *             on errors, such as giving values which are not supported.
	 */
	String serialize(List<? extends Object> array) throws JSONException;

	/**
	 * Serialize a JSONText array, given as a Java array type.
	 * 
	 * @param array
	 *            array of values, which may be of any type described above.
	 * @return String holding text
	 * @throws JSONException
	 *             on errors, such as giving values which are not supported.
	 */
	String serialize(Object[] array) throws JSONException;
}